<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Frequently asked questions (FAQ) | Butano Docs</title>
  <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,600i%7CSource+Code+Pro:400,400i,600" />
  <link rel="stylesheet" href="m-dark+documentation.compiled.css" />
  <link rel="icon" href="favicon-dark.png" type="image/png" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <meta name="theme-color" content="#22272e" />
</head>
<body>
<header><nav id="navigation">
  <div class="m-container">
    <div class="m-row">
      <span id="m-navbar-brand" class="m-col-t-8 m-col-m-none m-left-m">
        <a href="https://github.com/GValiente/butano">Butano</a> <span class="m-breadcrumb">|</span> <a href="index.html" class="m-thin">Docs</a>
      </span>
      <div class="m-col-t-4 m-hide-m m-text-right m-nopadr">
        <a href="#search" class="m-doc-search-icon" title="Search" onclick="return showSearch()"><svg style="height: 0.9rem;" viewBox="0 0 16 16">
          <path id="m-doc-search-icon-path" d="m6 0c-3.31 0-6 2.69-6 6 0 3.31 2.69 6 6 6 1.49 0 2.85-0.541 3.89-1.44-0.0164 0.338 0.147 0.759 0.5 1.15l3.22 3.79c0.552 0.614 1.45 0.665 2 0.115 0.55-0.55 0.499-1.45-0.115-2l-3.79-3.22c-0.392-0.353-0.812-0.515-1.15-0.5 0.895-1.05 1.44-2.41 1.44-3.89 0-3.31-2.69-6-6-6zm0 1.56a4.44 4.44 0 0 1 4.44 4.44 4.44 4.44 0 0 1-4.44 4.44 4.44 4.44 0 0 1-4.44-4.44 4.44 4.44 0 0 1 4.44-4.44z"/>
        </svg></a>
        <a id="m-navbar-show" href="#navigation" title="Show navigation"></a>
        <a id="m-navbar-hide" href="#" title="Hide navigation"></a>
      </div>
      <div id="m-navbar-collapse" class="m-col-t-12 m-show-m m-col-m-none m-right-m">
        <div class="m-row">
          <ol class="m-col-t-6 m-col-m-none">
            <li><a href="pages.html">Pages</a></li>
            <li><a href="modules.html">Modules</a></li>
          </ol>
          <ol class="m-col-t-6 m-col-m-none" start="3">
            <li><a href="namespaces.html">Namespaces</a></li>
            <li><a href="annotated.html">Classes</a></li>
            <li><a href="files.html">Files</a></li>
            <li class="m-show-m"><a href="#search" class="m-doc-search-icon" title="Search" onclick="return showSearch()"><svg style="height: 0.9rem;" viewBox="0 0 16 16">
              <use href="#m-doc-search-icon-path" />
            </svg></a></li>
          </ol>
        </div>
      </div>
    </div>
  </div>
</nav></header>
<main><article>
  <div class="m-container m-container-inflatable">
    <div class="m-row">
      <div class="m-col-l-10 m-push-l-1">
        <h1>
          Frequently asked questions (FAQ)
        </h1>
        <nav class="m-block m-default">
          <h3>Contents</h3>
          <ul>
            <li>
              <a href="#faq_general">General</a>
              <ul>
                <li><a href="#faq_how_do_i">How do I-</a></li>
                <li><a href="#faq_sell_money">Would I be able to sell my game made with Butano for money?</a></li>
                <li><a href="#faq_multiboot">Is it possible to use Butano to create multiboot games?</a></li>
                <li><a href="#faq_donate">Is there any way to donate to Butano?</a></li>
              </ul>
            </li>
            <li>
              <a href="#faq_programming">Programming</a>
              <ul>
                <li><a href="#faq_cpp">Can I use Butano without knowing C++?</a></li>
                <li><a href="#faq_ide">Is there any good free IDE for Butano projects out there?</a></li>
                <li><a href="#faq_incomplete_type">Why do I get an incomplete type error when trying to use a Butano class?</a></li>
                <li><a href="#faq_standard">Why can&#x27;t I use some standard functions and classes?</a></li>
                <li><a href="#faq_common_folder">Why can&#x27;t I use the content of the common folder in a new project?</a></li>
                <li><a href="#faq_subfolder">Can I use subfolders for code and assets?</a></li>
                <li><a href="#faq_stack_trace">What function or method call is the source of an error message?</a></li>
                <li><a href="#faq_error_after_update">Why do I get undefined reference errors after updating Butano?</a></li>
                <li><a href="#faq_destroy_ptr">How to destroy sprites and backgrounds?</a></li>
                <li><a href="#faq_destroy_optional">That&#x27;s cool, but how can I destroy and reload sprites and backgrounds as easy as possible?</a></li>
                <li><a href="#faq_float_double">Can I use float or double when coding for the GBA?</a></li>
                <li><a href="#faq_sprintf">How do I print a number in a string?</a></li>
                <li><a href="#faq_random_seed">How can I set the seed of a bn::random?</a></li>
                <li><a href="#faq_rect_odd_dimensions">Does bn::rect work with odd dimensions?</a></li>
                <li><a href="#faq_delta_time">How can I get the delta time?</a></li>
                <li><a href="#faq_wait_updates">Is there a way to stop running my code for a certain amount of time?</a></li>
                <li><a href="#faq_code_crash">How can I know what code makes my game crash?</a></li>
                <li><a href="#faq_screen_pixels">Can I directly manipulate screen pixels?</a></li>
                <li><a href="#faq_tonc_general_notes">Are there some more general notes on GBA programming out there?</a></li>
              </ul>
            </li>
            <li>
              <a href="#faq_memory">Memory</a>
              <ul>
                <li><a href="#faq_memory_containers">Why are there std like containers included with Butano?</a></li>
                <li><a href="#faq_memory_heap">So I shouldn&#x27;t use the heap?</a></li>
                <li><a href="#faq_memory_types">Why do I run out of memory so often?</a></li>
                <li><a href="#faq_memory_global_objects">Does Butano allow to declare bn::sprite_ptr or bn::regular_bg_ptr objects globally?</a></li>
                <li><a href="#faq_memory_arm_iwram">How can I generate ARM code in IWRAM?</a></li>
              </ul>
            </li>
            <li>
              <a href="#faq_images">Images</a>
              <ul>
                <li><a href="#faq_images_invalid_header_size">Why do I get an &quot;invalid header size&quot; error when I try to import a *.bmp file?</a></li>
              </ul>
            </li>
            <li>
              <a href="#faq_color">Colors</a>
              <ul>
                <li><a href="#faq_color_transparent">Which color is the transparent one?</a></li>
                <li><a href="#faq_color_backdrop">How can I set the backdrop color?</a></li>
                <li><a href="#faq_color_share_palettes">How to share the same color palette between sprites or backgrounds?</a></li>
                <li><a href="#faq_color_8bpp_palette_change">Why changing the color palette of an 8BPP sprite or background doesn&#x27;t work?</a></li>
              </ul>
            </li>
            <li>
              <a href="#faq_sprites">Sprites</a>
              <ul>
                <li><a href="#faq_sprites_top_left">Why are sprite coordinates relative to the center of the screen instead of the top-left corner?</a></li>
                <li><a href="#faq_sprites_multiple_8bpp">Why everything looks weird when I show two or more sprites with more than 16 colors?</a></li>
                <li><a href="#faq_sprites_item_from_ptr">Is there a way to get the bn::sprite_item used to create a bn::sprite_ptr?</a></li>
                <li><a href="#faq_sprites_scanline">Why whenever I have too many sprites on screen, some of them get cut off?</a></li>
                <li><a href="#faq_sprites_metasprites">Does Butano support metasprites?</a></li>
                <li><a href="#faq_sprites_hidden">Does hiding a sprite make it count towards the total number of allowed sprites?</a></li>
                <li><a href="#faq_sprites_sort_layers">Why do I get &quot;no more sprite sort layers available&quot; errors?</a></li>
                <li><a href="#faq_sprites_utf8_characters">How can I print UTF-8 characters like Japanese or Chinese ones?</a></li>
              </ul>
            </li>
            <li>
              <a href="#faq_backgrounds">Backgrounds</a>
              <ul>
                <li><a href="#faq_backgrounds_top_left">Why are background coordinates relative to the center of the screen instead of the top-left corner?</a></li>
                <li><a href="#faq_backgrounds_multiple_8bpp">Why everything looks weird when I show two or more backgrounds with more than 16 colors?</a></li>
                <li><a href="#faq_backgrounds_big">What&#x27;s a big background?</a></li>
                <li><a href="#faq_backgrounds_regular_affine">Why there are two types of backgrounds (regular and affine)?</a></li>
                <li><a href="#faq_backgrounds_animated">How can I show a background with animated tiles?</a></li>
                <li><a href="#faq_backgrounds_error_grit">Why can&#x27;t I import a regular background with 1024 or less tiles?</a></li>
                <li><a href="#faq_backgrounds_hidden">Does hiding a background make it count towards the total number of allowed backgrounds?</a></li>
              </ul>
            </li>
            <li>
              <a href="#faq_audio">Audio</a>
              <ul>
                <li><a href="#faq_audio_music_crash">Why the game crashes when some Direct Sound songs are played?</a></li>
                <li><a href="#faq_audio_music_wav">Why can&#x27;t I use a long *.wav file as music?</a></li>
                <li><a href="#faq_audio_music_missing_notes">Why there are missing notes when playing some Direct Sound songs?</a></li>
                <li><a href="#faq_audio_quality">How can I improve Direct Sound audio quality?</a></li>
              </ul>
            </li>
            <li>
              <a href="#faq_flash_carts">Flash carts</a>
              <ul>
                <li><a href="#faq_flash_carts_sram">Why my game runs fine on emulators but doesn&#x27;t work on a real GBA with a flash cart?</a></li>
                <li><a href="#faq_flash_carts_sram_old">Why SRAM works on emulators but doesn&#x27;t work with this old flash cart?</a></li>
              </ul>
            </li>
          </ul>
        </nav>
<section id="faq_general"><h2><a href="#faq_general">General</a></h2><section id="faq_how_do_i"><h3><a href="#faq_how_do_i">How do I-</a></h3><p>The best way to get started is to read the <a href="getting_started.html" class="m-doc">guide to download, install and start using Butano</a>.</p><p>After that, there are various <a href="examples.html" class="m-doc">examples</a> explaining most aspects of the engine.</p><p>At last, check how to <a href="import.html" class="m-doc">import</a> your own assets in a game and take a look at the <a href="modules.html">modules</a> page.</p><p>This page is worth a look too.</p></section><section id="faq_sell_money"><h3><a href="#faq_sell_money">Would I be able to sell my game made with Butano for money?</a></h3><p>Sure!</p><p>If you comply with <a href="https://github.com/GValiente/butano/blob/master/LICENSE">the Butano license</a> and <a href="https://github.com/GValiente/butano/blob/master/licenses">the licenses of the third party libraries</a> used by Butano, you can sell your game without issues.</p><p>If you use assets such as the sprite font from the <a href="examples.html" class="m-doc">examples</a> or from the <code>common</code> folder, you should also comply with their license. The licenses for these assets can be found in <a href="https://github.com/GValiente/butano/blob/master/credits">the credits folder</a>.</p></section><section id="faq_multiboot"><h3><a href="#faq_multiboot">Is it possible to use Butano to create multiboot games?</a></h3><p>It is possible, but not recommended as Butano footprint is too big for multiboot stuff, unless you want to make something <em>very</em> simple.</p><p>Multiboot ROMs <em>should be</em> generated when they have the suffix <code>_mb</code>:</p><p><code>TARGET := $(notdir $(CURDIR))_mb</code></p></section><section id="faq_donate"><h3><a href="#faq_donate">Is there any way to donate to Butano?</a></h3><p>Yes, you can make games with it and share them with your friends :)</p><p>You also can:</p><ul><li>Make good bug reports.</li><li>Help newbies.</li><li>Show cool splash screens in your games to say they were made with Butano.</li></ul></section></section><section id="faq_programming"><h2><a href="#faq_programming">Programming</a></h2><section id="faq_cpp"><h3><a href="#faq_cpp">Can I use Butano without knowing C++?</a></h3><p>While Butano is easy to use if you have some C++ skills, it is going to be hard to work with it if you don&#x27;t know nothing about C++, so you should learn a bit of C++ before diving into Butano.</p><p>After that, maybe you can learn both C++ and Butano at the same time while you make a game, but if you don&#x27;t want to have a hard time with Butano you should know the basics of C++ before messing with it.</p></section><section id="faq_ide"><h3><a href="#faq_ide">Is there any good free IDE for Butano projects out there?</a></h3><p>Take a look at the <a href="qt_creator.html" class="m-doc">Qt Creator setup guide</a>.</p></section><section id="faq_incomplete_type"><h3><a href="#faq_incomplete_type">Why do I get an incomplete type error when trying to use a Butano class?</a></h3><p>If you get an error message like these:</p><pre class="m-code"><span class="nl">error</span><span class="p">:</span><span class="w"> </span><span class="n">variable</span><span class="w"> </span><span class="err">&#39;</span><span class="n">bn</span><span class="o">::</span><span class="n">regular_bg_ptr</span><span class="w"> </span><span class="n">bg</span><span class="err">&#39;</span><span class="w"> </span><span class="n">has</span><span class="w"> </span><span class="n">initializer</span><span class="w"> </span><span class="n">but</span><span class="w"> </span><span class="n">incomplete</span><span class="w"> </span><span class="n">type</span>
<span class="nl">error</span><span class="p">:</span><span class="w"> </span><span class="n">invalid</span><span class="w"> </span><span class="n">use</span><span class="w"> </span><span class="n">of</span><span class="w"> </span><span class="n">incomplete</span><span class="w"> </span><span class="n">type</span><span class="w"> </span><span class="err">&#39;</span><span class="k">class</span><span class="w"> </span><span class="nc">bn</span><span class="o">::</span><span class="n">regular_bg_ptr</span><span class="err">&#39;</span>
<span class="nl">error</span><span class="p">:</span><span class="w"> </span><span class="n">aggregate</span><span class="w"> </span><span class="err">&#39;</span><span class="n">bn</span><span class="o">::</span><span class="n">fixed</span><span class="err">&#39;</span><span class="w"> </span><span class="n">has</span><span class="w"> </span><span class="n">incomplete</span><span class="w"> </span><span class="n">type</span><span class="w"> </span><span class="k">and</span><span class="w"> </span><span class="n">cannot</span><span class="w"> </span><span class="n">be</span><span class="w"> </span><span class="n">defined</span>
<span class="nl">error</span><span class="p">:</span><span class="w"> </span><span class="k">static</span><span class="w"> </span><span class="n">assertion</span><span class="w"> </span><span class="n">failed</span><span class="o">:</span><span class="w"> </span><span class="k">template</span><span class="w"> </span><span class="n">argument</span><span class="w"> </span><span class="n">must</span><span class="w"> </span><span class="n">be</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="n">complete</span><span class="w"> </span><span class="k">class</span><span class="w"> </span><span class="nc">or</span><span class="w"> </span><span class="n">an</span><span class="w"> </span><span class="n">unbounded</span><span class="w"> </span><span class="n">array</span></pre><p>It is almost always because of lack of included headers.</p><p>You can find the header of each Butano class in its documentation page.</p></section><section id="faq_standard"><h3><a href="#faq_standard">Why can&#x27;t I use some standard functions and classes?</a></h3><p>You need to link the standard system libraries to use standard functions like <code>strlen</code> and standard classes like <code>std::shared_ptr</code>.</p><p>To do that, the <code>DEFAULTLIBS</code> variable of the <code>Makefile</code> of your project must not be empty. For example:</p><p><code>DEFAULTLIBS := true</code></p><p>Remember to rebuild your project from scratch after modifying a <code>Makefile</code> (<code>make clean</code> before <code>make</code>).</p><p>Since you are now linking the standard system libraries, you must comply with their license. Also, don&#x27;t expect all standard functions and classes to work after linking the standard system libraries.</p></section><section id="faq_common_folder"><h3><a href="#faq_common_folder">Why can&#x27;t I use the content of the common folder in a new project?</a></h3><p>The <code>common</code> folder contains code and assets used by most Butano examples and tests.</p><p>It is not part of Butano (the library), so it is not included by default in new projects.</p><p>As the content of the <code>common</code> folder could change in future Butano versions, you should copy its content to your project if you want to use it:</p><ul><li>Copy <code>common</code> <code>*.cpp</code> files to the <code>src</code> folder of your project.</li><li>Copy <code>common</code> <code>*.h</code> files to the <code>include</code> folder of your project.</li><li>Do the same with the rest of the files in the <code>common</code> folder (<code>*.bmp</code>, <code>*.json</code>, etc).</li></ul></section><section id="faq_subfolder"><h3><a href="#faq_subfolder">Can I use subfolders for code and assets?</a></h3><p>Yes, but you need to add them to the <code>Makefile</code> of your project.</p><p>For example:</p><p><code>SOURCES := src src/subfolder</code></p></section><section id="faq_stack_trace"><h3><a href="#faq_stack_trace">What function or method call is the source of an error message?</a></h3><p>You can enable stack trace logging in the <code>Makefile</code> of your project, so that when an error message is displayed, the current stack trace will be logged.</p><p>To enable stack trace logging, the <code>STACKTRACE</code> variable must not be empty. For example:</p><p><code>STACKTRACE := true</code></p><p>Remember to rebuild your project from scratch after modifying a <code>Makefile</code> (<code>make clean</code> before <code>make</code>).</p><p>If everything went well, the error message should indicate that the stack trace has been logged. In that case, open the logs window of your emulator and the mangled stack trace should be there. To demangle it, you can use <a href="http://demangler.com/">demangler.com</a> for example.</p></section><section id="faq_error_after_update"><h3><a href="#faq_error_after_update">Why do I get undefined reference errors after updating Butano?</a></h3><p>If after updating Butano you get error messages like this one:</p><p>&lsquo;error: undefined reference to &#x27;bn::reciprocal_lut_16&rsquo;`</p><p>They usually go away with a full rebuild of your project (<code>make clean</code> before <code>make</code>).</p><p>Also make sure you update <a href="https://devkitpro.org/">devkitARM</a> when you update Butano, since some Butano features don&#x27;t work with older devkitARM releases.</p></section><section id="faq_destroy_ptr"><h3><a href="#faq_destroy_ptr">How to destroy sprites and backgrounds?</a></h3><p><a href="classbn_1_1sprite__ptr.html" class="m-doc">bn::<wbr />sprite_ptr</a>, <a href="classbn_1_1regular__bg__ptr.html" class="m-doc">bn::<wbr />regular_bg_ptr</a> and all Butano classes that end with the <code>_ptr</code> suffix are <code>std::shared_ptr</code> like smart pointers that retains shared ownership of a hardware resource.</p><p>In the case of <a href="classbn_1_1sprite__ptr.html" class="m-doc">bn::<wbr />sprite_ptr</a>, several <a href="classbn_1_1sprite__ptr.html" class="m-doc">bn::<wbr />sprite_ptr</a> objects may own the same sprite. The sprite is released when the last remaining <a href="classbn_1_1sprite__ptr.html" class="m-doc">bn::<wbr />sprite_ptr</a> owning it is destroyed.</p><p>If you want to learn more about <code>std::shared_ptr</code>, you can read:</p><ul><li><a href="https://www.geeksforgeeks.org/auto_ptr-unique_ptr-shared_ptr-weak_ptr-2">A basic introduction of standard smart pointers</a>.</li><li><a href="https://docs.microsoft.com/en-us/cpp/cpp/how-to-create-and-use-shared-ptr-instances?view=msvc-160">A std::<wbr />shared_ptr usage guide</a>.</li></ul></section><section id="faq_destroy_optional"><h3><a href="#faq_destroy_optional">That&#x27;s cool, but how can I destroy and reload sprites and backgrounds as easy as possible?</a></h3><p><a href="classbn_1_1optional.html" class="m-doc">bn::<wbr />optional</a> helps to unload and reload hardware resources easily:</p><pre class="m-code"><span class="c1">// bg_optional is empty:</span>
<span class="n">bn</span><span class="o">::</span><span class="n">optional</span><span class="o">&lt;</span><span class="n">bn</span><span class="o">::</span><span class="n">regular_bg_ptr</span><span class="o">&gt;</span><span class="w"> </span><span class="n">bg_optional</span><span class="p">;</span>

<span class="c1">// bg_optional now contains the background specified by bn::regular_bg_items::bg1:</span>
<span class="n">bg_optional</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">bn</span><span class="o">::</span><span class="n">regular_bg_items</span><span class="o">::</span><span class="n">bg1</span><span class="p">.</span><span class="n">create_bg</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="mi">0</span><span class="p">);</span>

<span class="c1">// bg_optional is empty again:</span>
<span class="n">bg_optional</span><span class="p">.</span><span class="n">reset</span><span class="p">();</span>

<span class="c1">// bg_optional now contains the background specified by bn::regular_bg_items::bg2:</span>
<span class="n">bg_optional</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">bn</span><span class="o">::</span><span class="n">regular_bg_items</span><span class="o">::</span><span class="n">bg2</span><span class="p">.</span><span class="n">create_bg</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="mi">0</span><span class="p">);</span></pre></section><section id="faq_float_double"><h3><a href="#faq_float_double">Can I use float or double when coding for the GBA?</a></h3><p>Modern CPUs have dedicated hardware for processing <code>float</code>s and <code>double</code>s. The GBA doesn&#x27;t have it, so you&#x27;re left with two choices:</p><ul><li>Using <code>float</code>s and <code>double</code>s emulated in software (<em>very</em> slow).</li><li>Using fixed point arithmetic, which is just integer arithmetic with a few extra steps.</li></ul><p>Butano provides <a href="namespacebn.html#a0de0484a51e353c5b48db21590f4dfc9" class="m-doc">bn::<wbr />fixed</a>, which tries to be as close as possible to a <code>float</code> with fixed point arithmetic. Use it when you want to work with numbers with decimal points.</p></section><section id="faq_sprintf"><h3><a href="#faq_sprintf">How do I print a number in a string?</a></h3><p><em>Don&#x27;t</em> use <code>sprintf</code>, <code>std::ostringstream</code> or anything else from the standard library, because:</p><ul><li>Butano functions for printing numbers in strings can be more than 5 times faster than the standard functions.</li><li>Standard functions can take more than 4KB of IWRAM.</li><li>Standard functions sometimes can&#x27;t be used because they throw link errors.</li></ul><p>If you want to print a number in a string with Butano, <a href="group__string.html#ga20a7eaa9f61194a3cce900516a2918e1" class="m-doc">bn::<wbr />to_string</a> provides the easiest way to do it:</p><pre class="m-code"><span class="n">bn</span><span class="o">::</span><span class="n">string</span><span class="o">&lt;</span><span class="mi">16</span><span class="o">&gt;</span><span class="w"> </span><span class="n">string</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">bn</span><span class="o">::</span><span class="n">to_string</span><span class="o">&lt;</span><span class="mi">16</span><span class="o">&gt;</span><span class="p">(</span><span class="n">number</span><span class="p">);</span></pre><p>If you want to compose a string with multiple numbers, you can use <a href="classbn_1_1ostringstream.html" class="m-doc">bn::<wbr />ostringstream</a> too:</p><pre class="m-code"><span class="n">bn</span><span class="o">::</span><span class="n">string</span><span class="o">&lt;</span><span class="mi">64</span><span class="o">&gt;</span><span class="w"> </span><span class="n">string</span><span class="p">;</span>
<span class="n">bn</span><span class="o">::</span><span class="n">ostringstream</span><span class="w"> </span><span class="nf">string_stream</span><span class="p">(</span><span class="n">string</span><span class="p">);</span>
<span class="n">string_stream</span><span class="w"> </span><span class="o">&lt;&lt;</span><span class="w"> </span><span class="s">&quot;Text: &quot;</span><span class="p">;</span>
<span class="n">string_stream</span><span class="w"> </span><span class="o">&lt;&lt;</span><span class="w"> </span><span class="mi">123</span><span class="p">;</span>
<span class="n">string_stream</span><span class="w"> </span><span class="o">&lt;&lt;</span><span class="w"> </span><span class="s">&quot; - &quot;</span><span class="p">;</span>
<span class="n">string_stream</span><span class="w"> </span><span class="o">&lt;&lt;</span><span class="w"> </span><span class="n">number</span><span class="p">;</span></pre></section><section id="faq_random_seed"><h3><a href="#faq_random_seed">How can I set the seed of a bn::random?</a></h3><p>If you want to do that, use <a href="classbn_1_1seed__random.html" class="m-doc">bn::<wbr />seed_random</a> instead.</p></section><section id="faq_rect_odd_dimensions"><h3><a href="#faq_rect_odd_dimensions">Does bn::rect work with odd dimensions?</a></h3><p>Since it takes a center point as position instead of a top-left point, <a href="classbn_1_1rect.html" class="m-doc">bn::<wbr />rect</a> has problems with odd dimensions.</p><p>If you need to handle odd dimensions, use <a href="classbn_1_1top__left__rect.html" class="m-doc">bn::<wbr />top_left_rect</a> instead.</p></section><section id="faq_delta_time"><h3><a href="#faq_delta_time">How can I get the delta time?</a></h3><p>You can usually assume than your game is running at 60FPS, so to wait one second you should call <a href="namespacebn_1_1core.html#aa849bfe482eb6964e3a29f9eba78f7b6" class="m-doc">bn::<wbr />core::<wbr />update</a> 60 times. In this case, the delta time (the time elapsed between two <a href="namespacebn_1_1core.html#aa849bfe482eb6964e3a29f9eba78f7b6" class="m-doc">bn::<wbr />core::<wbr />update</a> calls) is always one frame, or <code>1 / 60</code> seconds.</p><p>However, if your game is so choppy that it has variable frame rate (it shouldn&#x27;t), you can get the number of frames that were missed in the last <a href="namespacebn_1_1core.html#aa849bfe482eb6964e3a29f9eba78f7b6" class="m-doc">bn::<wbr />core::<wbr />update</a> call with <a href="namespacebn_1_1core.html#a98c2b2065c2694d96b695a6076df8506" class="m-doc">bn::<wbr />core::<wbr />last_missed_frames</a>. The delta time is the number of missed frames plus one:</p><pre class="m-code"><span class="kt">int</span><span class="w"> </span><span class="n">elapsed_frames</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">bn</span><span class="o">::</span><span class="n">core</span><span class="o">::</span><span class="n">last_missed_frames</span><span class="p">()</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span></pre></section><section id="faq_wait_updates"><h3><a href="#faq_wait_updates">Is there a way to stop running my code for a certain amount of time?</a></h3><p>Since you can usually assume than your game is running at 60FPS, for example you can wait one second with this code:</p><pre class="m-code"><span class="k">for</span><span class="p">(</span><span class="kt">int</span><span class="w"> </span><span class="n">index</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span><span class="w"> </span><span class="n">index</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="mi">60</span><span class="p">;</span><span class="w"> </span><span class="o">++</span><span class="n">index</span><span class="p">)</span>
<span class="p">{</span>
<span class="w">    </span><span class="n">bn</span><span class="o">::</span><span class="n">core</span><span class="o">::</span><span class="n">update</span><span class="p">();</span>
<span class="p">}</span></pre></section><section id="faq_code_crash"><h3><a href="#faq_code_crash">How can I know what code makes my game crash?</a></h3><p><a href="https://problemkaputt.de/gba.htm">No$gba</a> exception system allows to catch common programming errors. When an exception is triggered, No$gba can stop the execution of the ROM and show the code that has triggered the exception. Please check the <a href="nocashgba_exception.html" class="m-doc">No$gba exception setup guide</a> if you want to try it.</p><p>As always, you also can remove code until the crash goes away.</p></section><section id="faq_screen_pixels"><h3><a href="#faq_screen_pixels">Can I directly manipulate screen pixels?</a></h3><p>Butano doesn&#x27;t support bitmap video modes for now, so there&#x27;s no easy way to do that.</p></section><section id="faq_tonc_general_notes"><h3><a href="#faq_tonc_general_notes">Are there some more general notes on GBA programming out there?</a></h3><p><a href="https://gbadev.net/tonc/first.html#sec-notes">I&#x27;m glad you asked</a>.</p></section></section><section id="faq_memory"><h2><a href="#faq_memory">Memory</a></h2><section id="faq_memory_containers"><h3><a href="#faq_memory_containers">Why are there std like containers included with Butano?</a></h3><p>Butano containers differ from the standard library ones in two important points:</p><ul><li>They don&#x27;t use the heap, their content is always on the stack.</li><li>They don&#x27;t throw exceptions. <a href="group__assert.html" class="m-doc">Asserts</a> are used instead.</li></ul><p>Since avoiding heap usage and exceptions is usually good for GBA development, use Butano containers whenever possible.</p><p>Keep in mind that unlike most Butano containers, <a href="classbn_1_1unique__ptr.html" class="m-doc">bn::<wbr />unique_ptr</a> uses the heap instead of the stack.</p></section><section id="faq_memory_heap"><h3><a href="#faq_memory_heap">So I shouldn&#x27;t use the heap?</a></h3><p>Since heap usage is slow and the heap allocator included with Butano is not very fast, avoid heap usage whenever possible.</p><p>Also, remember to call <a href="namespacebn_1_1core.html#ae44eeedf2d7cadbe8d8d6990e209f46d" class="m-doc">bn::<wbr />core::<wbr />init</a> before using the heap.</p></section><section id="faq_memory_types"><h3><a href="#faq_memory_types">Why do I run out of memory so often?</a></h3><p>Besides VRAM and such, the GBA provides two memory banks:</p><ul><li>IWRAM: 32KB fast RAM.</li><li>EWRAM: 256KB slow RAM.</li></ul><p>Data is allocated in IWRAM by default, so it is common to run out of memory if you don&#x27;t use EWRAM.</p><p>To place data in EWRAM, you can:</p><ul><li>Allocate memory in the heap, since it is placed in EWRAM.</li><li>Declare static data with the <code>BN_DATA_EWRAM</code> macro: <code class="m-code"><span class="n">BN_DATA_EWRAM</span><span class="w"> </span><span class="n">static_data</span><span class="w"> </span><span class="n">data</span><span class="p">;</span></code></li></ul><p>However, if the data is read only, you can avoid wasting RAM by placing it in ROM with the <code>constexpr</code> qualifier: <code class="m-code"><span class="k">constexpr</span><span class="w"> </span><span class="n">const_data</span><span class="w"> </span><span class="n">data</span><span class="p">;</span></code></p><p><a href="namespacebn_1_1memory.html" class="m-doc">bn::<wbr />memory</a> provides functions to query available and used RAM, like <a href="namespacebn_1_1memory.html#a0d18408ebe87f9a35fe7ccd7dbd4f23a" class="m-doc">bn::<wbr />memory::<wbr />used_stack_iwram</a> and <a href="namespacebn_1_1memory.html#a84365d5194745caf934d0b42ebd0b775" class="m-doc">bn::<wbr />memory::<wbr />used_static_iwram</a>.</p><p>To avoid running out of IWRAM, Butano Fighter and Varooom 3D place all scenes in EWRAM. Check their <code>main.cpp</code> files to see how it works.</p></section><section id="faq_memory_global_objects"><h3><a href="#faq_memory_global_objects">Does Butano allow to declare bn::sprite_ptr or bn::regular_bg_ptr objects globally?</a></h3><p>In general, you should not do anything with Butano before calling <a href="namespacebn_1_1core.html#ae44eeedf2d7cadbe8d8d6990e209f46d" class="m-doc">bn::<wbr />core::<wbr />init</a>, including creating global Butano objects and allocating memory in the heap.</p><p>If you want to declare global Butano objects, you can do something like this instead:</p><pre class="m-code"><span class="k">struct</span><span class="w"> </span><span class="nc">global_data</span>
<span class="p">{</span>
<span class="w">    </span><span class="n">bn</span><span class="o">::</span><span class="n">sprite_ptr</span><span class="w"> </span><span class="n">sprite</span><span class="p">;</span>
<span class="w">    </span><span class="n">bn</span><span class="o">::</span><span class="n">regular_bg_ptr</span><span class="w"> </span><span class="n">bg</span><span class="p">;</span>
<span class="p">};</span>

<span class="n">global_data</span><span class="o">*</span><span class="w"> </span><span class="n">global_ptr</span><span class="p">;</span>

<span class="kt">int</span><span class="w"> </span><span class="nf">main</span><span class="p">()</span>
<span class="p">{</span>
<span class="w">    </span><span class="n">bn</span><span class="o">::</span><span class="n">core</span><span class="o">::</span><span class="n">init</span><span class="p">();</span>

<span class="w">    </span><span class="n">global_data</span><span class="w"> </span><span class="n">global_instance</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span>
<span class="w">        </span><span class="n">bn</span><span class="o">::</span><span class="n">sprite_items</span><span class="o">::</span><span class="n">sprite_item</span><span class="p">.</span><span class="n">create_sprite</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="mi">0</span><span class="p">),</span>
<span class="w">        </span><span class="n">bn</span><span class="o">::</span><span class="n">regular_bg_items</span><span class="o">::</span><span class="n">bg_item</span><span class="p">.</span><span class="n">create_bg</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="mi">0</span><span class="p">)</span>
<span class="w">    </span><span class="p">};</span>

<span class="w">    </span><span class="n">global_ptr</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">&amp;</span><span class="n">global_instance</span><span class="p">;</span>

<span class="w">    </span><span class="c1">// ...</span>
<span class="p">}</span></pre><p>With that, you can access global Butano objects from anywhere in your project with this code:</p><pre class="m-code"><span class="n">global_ptr</span><span class="o">-&gt;</span><span class="n">sprite</span><span class="p">.</span><span class="n">set_position</span><span class="p">(</span><span class="mi">50</span><span class="p">,</span><span class="w"> </span><span class="mi">50</span><span class="p">);</span></pre></section><section id="faq_memory_arm_iwram"><h3><a href="#faq_memory_arm_iwram">How can I generate ARM code in IWRAM?</a></h3><p>By default, functions and methods are compiled to Thumb code and placed in ROM. If you want to increase the performance of a function/method, a good way is to compile it to ARM code and place it in IWRAM.</p><p>To do it, you have to:</p><ul><li>Place the <code>BN_CODE_IWRAM</code> macro before the function/method declaration to indicate its section. For example: <code class="m-code"><span class="n">BN_CODE_IWRAM</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="n">my_function</span><span class="p">(</span><span class="kt">int</span><span class="w"> </span><span class="n">arg</span><span class="p">);</span></code></li><li>Place the function/method definition in a file with extension <code>.bn_iwram.cpp</code>.</li></ul><p>For example, the <code>world_map</code> example generates ARM code in IWRAM for the <code>load_attributes</code> function.</p><p>Keep in mind that IWRAM is small, so you shouldn&#x27;t place too much code in it.</p></section></section><section id="faq_images"><h2><a href="#faq_images">Images</a></h2><section id="faq_images_invalid_header_size"><h3><a href="#faq_images_invalid_header_size">Why do I get an &quot;invalid header size&quot; error when I try to import a *.bmp file?</a></h3><p>If you get that error when importing a <code>*.bmp</code> file, it probably means that it contains unsupported features, such as:</p><ul><li>Compression.</li><li>Color space information.</li><li>Non-indexed colors.</li></ul><p>Please check the <a href="import.html#import_image" class="m-doc">Images</a> import guide to learn more about how to generate supported <code>*.bmp</code> files.</p></section></section><section id="faq_color"><h2><a href="#faq_color">Colors</a></h2><section id="faq_color_transparent"><h3><a href="#faq_color_transparent">Which color is the transparent one?</a></h3><p>Butano supports 16 or 256 color images only, so they must have a color palette.</p><p>The transparent color is the first one in the color palette, so in order to change it you should use a bitmap editor with color palette manipulation tools, like <a href="https://github.com/gb-archive/usenti">Usenti</a>:</p><img class="m-image" src="import_usenti.png" alt="Image" /></section><section id="faq_color_backdrop"><h3><a href="#faq_color_backdrop">How can I set the backdrop color?</a></h3><p>The transparent or the backdrop color (displayed color when nothing else is) is the first one in the backgrounds palette.</p><p>You can override its default value with <a href="namespacebn_1_1bg__palettes.html#a6b793b88f09ac5683bc6e6a47a833937" class="m-doc">bn::<wbr />bg_palettes::<wbr />set_transparent_color</a>.</p></section><section id="faq_color_share_palettes"><h3><a href="#faq_color_share_palettes">How to share the same color palette between sprites or backgrounds?</a></h3><p>If two sprites or backgrounds have the same colors, by default they share the same color palette.</p><p>Keep in mind that unused colors are also taken into account when deciding if two color palettes are equal or not.</p></section><section id="faq_color_8bpp_palette_change"><h3><a href="#faq_color_8bpp_palette_change">Why changing the color palette of an 8BPP sprite or background doesn&#x27;t work?</a></h3><p>Since the GBA has only 256 colors for sprites, if you use two sprites with more than 16 colors at the same time, Butano assumes that they have the same color palette (same colors in the same order).</p><p>So if you change the palette of an 8BPP sprite with a new palette item, Butano assumes that the palette created with the palette item is the same as the old one and doesn&#x27;t update the colors of the sprite:</p><pre class="m-code"><span class="n">sprite</span><span class="p">.</span><span class="n">set_palette</span><span class="p">(</span><span class="n">palette_item</span><span class="p">);</span></pre><p>If what you want to do is to update the colors of the sprite, you have to retrieve the palette of the sprite and update its colors:</p><pre class="m-code"><span class="n">bn</span><span class="o">::</span><span class="n">sprite_palette_ptr</span><span class="w"> </span><span class="n">sprite_palette</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">sprite</span><span class="p">.</span><span class="n">palette</span><span class="p">();</span>
<span class="n">sprite_palette</span><span class="p">.</span><span class="n">set_colors</span><span class="p">(</span><span class="n">palette_item</span><span class="p">);</span></pre><p>The same happens with 8BPP backgrounds.</p></section></section><section id="faq_sprites"><h2><a href="#faq_sprites">Sprites</a></h2><section id="faq_sprites_top_left"><h3><a href="#faq_sprites_top_left">Why are sprite coordinates relative to the center of the screen instead of the top-left corner?</a></h3><p>There&#x27;s no way to make sprite coordinates relative to the top-left corner of the screen by default.</p><p>However, if you don&#x27;t like it, you can always use the <code>top_left</code> methods to specify coordinates relative to the top-left corner of the screen. They&#x27;re a bit slower than the regular ones, though.</p></section><section id="faq_sprites_multiple_8bpp"><h3><a href="#faq_sprites_multiple_8bpp">Why everything looks weird when I show two or more sprites with more than 16 colors?</a></h3><p>Since the GBA has only 256 colors for sprites, if you use two sprites with more than 16 colors at the same time, Butano assumes that they have the same color palette (same colors in the same order).</p><p>So if you are going to show multiple sprites with more than 16 colors at the same time, use the same color palette with all of them (in the same scene of course, sprites shown in different scenes can have different color palettes).</p></section><section id="faq_sprites_item_from_ptr"><h3><a href="#faq_sprites_item_from_ptr">Is there a way to get the bn::sprite_item used to create a bn::sprite_ptr?</a></h3><p>No :)</p></section><section id="faq_sprites_scanline"><h3><a href="#faq_sprites_scanline">Why whenever I have too many sprites on screen, some of them get cut off?</a></h3><p>If you show too many sprites on screen (especially if they&#x27;re rotated or scaled), they won&#x27;t be rendered because the GBA has a <a href="https://problemkaputt.de/gbatek-lcd-obj-overview.htm">maximum number of sprite pixels per scanline</a>.</p><p>You can try to get around this limitation by showing sprites without rotation or scaling, or even better, using backgrounds instead of sprites.</p></section><section id="faq_sprites_metasprites"><h3><a href="#faq_sprites_metasprites">Does Butano support metasprites?</a></h3><p>Metasprites (groups of regular sprites that together represent one single bigger sprite) are not supported by Butano.</p></section><section id="faq_sprites_hidden"><h3><a href="#faq_sprites_hidden">Does hiding a sprite make it count towards the total number of allowed sprites?</a></h3><p>Hidden sprites are not committed to the GBA, but they still take resources like color palettes and VRAM.</p><p>The easiest way to increase the maximum number of hidden sprites allowed for a particular project is to set it in the <code>USERFLAGS</code> of its <code>Makefile</code>.</p><p>For example, to set the maximum number of hidden sprites to 256:</p><p><code>USERFLAGS := -DBN_CFG_SPRITES_MAX_ITEMS=256</code></p><p>Remember to rebuild your project from scratch after modifying a <code>Makefile</code> (<code>make clean</code> before <code>make</code>).</p></section><section id="faq_sprites_sort_layers"><h3><a href="#faq_sprites_sort_layers">Why do I get &quot;no more sprite sort layers available&quot; errors?</a></h3><p>Sprites are grouped in layers depending of their background priority and z order, so to reduce memory usage and improve performance, please use as few unique z orders as possible.</p><p>If you still need to increase the maximum number of sprite sort layers available for a particular project, the easiest way to do it is to set it in the <code>USERFLAGS</code> of its <code>Makefile</code>.</p><p>For example, to set the maximum number of sprite sort layers to 32:</p><p><code>USERFLAGS := -DBN_CFG_SPRITES_MAX_SORT_LAYERS=32</code></p><p>Remember to rebuild your project from scratch after modifying a <code>Makefile</code> (<code>make clean</code> before <code>make</code>).</p></section><section id="faq_sprites_utf8_characters"><h3><a href="#faq_sprites_utf8_characters">How can I print UTF-8 characters like Japanese or Chinese ones?</a></h3><p><a href="classbn_1_1sprite__text__generator.html" class="m-doc">bn::<wbr />sprite_text_generator</a> already supports UTF-8 characters rendering, but the <a href="classbn_1_1sprite__font.html" class="m-doc">bn::<wbr />sprite_font</a> instances used in the <a href="examples.html" class="m-doc">examples</a> don&#x27;t provide Japanese or Chinese characters, so you will have to make a new one with them.</p></section></section><section id="faq_backgrounds"><h2><a href="#faq_backgrounds">Backgrounds</a></h2><section id="faq_backgrounds_top_left"><h3><a href="#faq_backgrounds_top_left">Why are background coordinates relative to the center of the screen instead of the top-left corner?</a></h3><p>There&#x27;s no way to make background coordinates relative to the top-left corner of the screen by default.</p><p>If you don&#x27;t like it, you can always use the <code>top_left</code> methods to specify coordinates relative to the top-left corner of the screen. They&#x27;re a bit slower than the regular ones, though.</p></section><section id="faq_backgrounds_multiple_8bpp"><h3><a href="#faq_backgrounds_multiple_8bpp">Why everything looks weird when I show two or more backgrounds with more than 16 colors?</a></h3><p>Since the GBA has only 256 colors for tiled backgrounds, if you use two 8BPP backgrounds, Butano assumes that they have the same color palette (same colors in the same order).</p><p>So if you are going to show multiple 8BPP backgrounds, you can:</p><ul><li>Use the same color palette with all of them (in the same scene of course, backgrounds shown in different scenes can have different color palettes).</li><li>Change their BPP mode to 4BPP, so each background can have its own color palette with more than 16 colors.</li></ul></section><section id="faq_backgrounds_big"><h3><a href="#faq_backgrounds_big">What&#x27;s a big background?</a></h3><p>The GBA only supports some fixed sizes for background maps.</p><p>However, Butano allows to manage background maps with any size up to 16384 pixels and multiple of 256 pixels. These special background maps and the backgrounds that display them are called big maps/backgrounds.</p><p>Try to avoid big backgrounds whenever possible, because they are slower CPU wise.</p></section><section id="faq_backgrounds_regular_affine"><h3><a href="#faq_backgrounds_regular_affine">Why there are two types of backgrounds (regular and affine)?</a></h3><p>It seems it is always better to use affine backgrounds, since they can be rotated, scaled, etc. and its size can be up to 1024x1024 pixels without becoming big backgrounds.</p><p>However, compared to regular backgrounds, affine backgrounds have these limitations:</p><ul><li>Only two of them can be displayed at the same time, instead of four.</li><li>They don&#x27;t support 16 color tiles, only 256 color ones.</li><li>They only support up to 256 different tiles, instead of 1024.</li><li>They don&#x27;t support flipped tiles.</li></ul><p>Because of these limitations, you should avoid affine backgrounds whenever possible.</p></section><section id="faq_backgrounds_animated"><h3><a href="#faq_backgrounds_animated">How can I show a background with animated tiles?</a></h3><p>There are two ways, the easy one and the powerful one:</p><ul><li>If you only want to show some basic tile animation, such the water or the grass tiles in top-down RPGs, you can use one of these actions: <a href="classbn_1_1regular__bg__animate__action.html" class="m-doc">bn::<wbr />regular_bg_animate_action</a>, <a href="classbn_1_1regular__bg__cached__animate__action.html" class="m-doc">bn::<wbr />regular_bg_cached_animate_action</a>, <a href="classbn_1_1affine__bg__animate__action.html" class="m-doc">bn::<wbr />affine_bg_animate_action</a> and <a href="classbn_1_1affine__bg__cached__animate__action.html" class="m-doc">bn::<wbr />affine_bg_cached_animate_action</a>. The <code>regular_bgs</code> and <code>affine_bgs</code> examples show how to use some of them.</li><li>If you want to show something more advanced, you need to manage the background map by yourself. The <code>dynamic_regular_bg</code> and <code>dynamic_affine_bg</code> examples show how to do it.</li></ul></section><section id="faq_backgrounds_error_grit"><h3><a href="#faq_backgrounds_error_grit">Why can&#x27;t I import a regular background with 1024 or less tiles?</a></h3><p>If you get this error when trying to import a regular background with 1024 or less tiles:</p><p><code>error: Regular BGs with more than 1024 tiles not supported: 1025</code></p><p>Or you get this error when importing an affine background with 256 or less tiles:</p><p><code>error: Affine BGs with more than 256 tiles not supported: 257</code></p><p>Your image is fine, but <a href="https://github.com/devkitPro/grit">grit</a> (the tool used by Butano to import images) is generating unneeded extra tiles.</p><p>The only workaround that I know of is reducing detail in your input image until the tiles count of the generated background is valid.</p><p>However, if you are working with unique tiles to generate a dynamic background, importing background tiles only instead of a background with map should work. Check <a href="import.html#import_regular_bg_tiles" class="m-doc">Regular background tiles</a>, <a href="import.html#import_affine_bg_tiles" class="m-doc">Affine background tiles</a>, the <code>dynamic_regular_bg</code> example and the <code>dynamic_affine_bg</code> example for that.</p></section><section id="faq_backgrounds_hidden"><h3><a href="#faq_backgrounds_hidden">Does hiding a background make it count towards the total number of allowed backgrounds?</a></h3><p>Hidden backgrounds are not committed to the GBA, but they still take resources like color palettes and VRAM.</p><p>The easiest way to increase the maximum number of hidden backgrounds allowed for a particular project is to set it in the <code>USERFLAGS</code> of its <code>Makefile</code>.</p><p>For example, to set the maximum number of hidden backgrounds to 8:</p><p><code>USERFLAGS := -DBN_CFG_BGS_MAX_ITEMS=8</code></p><p>Remember to rebuild your project from scratch after modifying a <code>Makefile</code> (<code>make clean</code> before <code>make</code>).</p></section></section><section id="faq_audio"><h2><a href="#faq_audio">Audio</a></h2><section id="faq_audio_music_crash"><h3><a href="#faq_audio_music_crash">Why the game crashes when some Direct Sound songs are played?</a></h3><p>By default, Butano uses the excellent <a href="https://blocksds.skylyrac.net/docs/maxmod/index.html">Maxmod</a> library for Direct Sound audio support.</p><p>It provides impressive performance and support for lots of module music formats, but unfortunately it crashes with some songs.</p><p>Sometimes it helps to change song&#x27;s file format (for example, from <code>*.xm</code> to <code>*.it</code>). You can use <a href="https://openmpt.org/">OpenMPT</a> to do that.</p><p>Keep in mind that the Maxmod&#x27;s conversion tool provided by <a href="https://blocksds.skylyrac.net">BlocksDS</a> is more robust than the one provided by <a href="https://devkitpro.org/">devkitARM</a>, so using Butano with <a href="https://wonderful.asie.pl/">Wonderful Toolchain</a> could make your song work.</p><p>If your song still crashes after trying <a href="https://wonderful.asie.pl/">Wonderful Toolchain</a>, you can try to create a new issue in the <a href="https://github.com/blocksds/sdk/issues">Maxmod&#x27;s GitHub issues</a> page.</p></section><section id="faq_audio_music_wav"><h3><a href="#faq_audio_music_wav">Why can&#x27;t I use a long *.wav file as music?</a></h3><p><a href="https://blocksds.skylyrac.net/docs/maxmod/index.html">Maxmod</a> doesn&#x27;t allow to play long <code>*.wav</code> files as music, unfortunately.</p><p>The maximum length of sound samples is also small, so if you try to play a long <code>*.wav</code> file as a sound effect, it should stop after a few seconds.</p><p>What you can do is to split your long <code>*.wav</code> file in small pieces and put them in a module file (files with <code>*.mod</code>, <code>*.xm</code>, <code>*.s3m</code> and <code>*.it</code> extensions). You can use <a href="https://sox.sourceforge.net/">SoX</a> to split the long <code>*.wav</code> file and <a href="https://openmpt.org/">OpenMPT</a> to create the final module file.</p><p>You also can use <a href="https://github.com/Fralacticus/gba-wav-to-s3m-converter">GBA Wav to S3m Converter</a>, a tool that generates a <code>*.s3m</code> file from a long <code>*.wav</code> automatically.</p></section><section id="faq_audio_music_missing_notes"><h3><a href="#faq_audio_music_missing_notes">Why there are missing notes when playing some Direct Sound songs?</a></h3><p>If a song doesn&#x27;t have more channels than the maximum number of active Direct Sound music channels specified by <a href="group__music.html#ga9ec36de1eb7cd32376a5765bf3d6a63d" class="m-doc">BN_<wbr />CFG_<wbr />AUDIO_<wbr />MAX_<wbr />MUSIC_<wbr />CHANNELS</a>, as before, sometimes it helps to change its file format (for example, from <code>*.xm</code> to <code>*.it</code>). You can use <a href="https://openmpt.org/">OpenMPT</a> to do that.</p></section><section id="faq_audio_quality"><h3><a href="#faq_audio_quality">How can I improve Direct Sound audio quality?</a></h3><p>If you have some free CPU left, you can increase Direct Sound audio mixing rate to improve its quality.</p><p>The easiest way to specify Direct Sound audio mixing rate for a particular project is to set it in the <code>USERFLAGS</code> of its <code>Makefile</code>.</p><p>For example, to set Direct Sound audio mixing rate to 21KHz:</p><p><code>USERFLAGS := -DBN_CFG_AUDIO_MIXING_RATE=BN_AUDIO_MIXING_RATE_21_KHZ</code></p><p>Remember to rebuild your project from scratch after modifying a <code>Makefile</code> (<code>make clean</code> before <code>make</code>).</p><p>Available Direct Sound mixing rates are <a href="group__audio.html" class="m-doc">here</a>.</p></section></section><section id="faq_flash_carts"><h2><a href="#faq_flash_carts">Flash carts</a></h2><section id="faq_flash_carts_sram"><h3><a href="#faq_flash_carts_sram">Why my game runs fine on emulators but doesn&#x27;t work on a real GBA with a flash cart?</a></h3><p>Emulators usually initialize SRAM with zeros, while some flash carts don&#x27;t. You should check if SRAM is formatted and format it if it isn&#x27;t. The <code>sram</code> example shows how to do it.</p><p>Also, some flash carts allow to improve commercial games with patches like <code>saver patch</code>, <code>enable restart</code>, <code>enable real time save</code>, etc. These patches can break homebrew games, so try to disable some or all of them if you run into any issues.</p></section><section id="faq_flash_carts_sram_old"><h3><a href="#faq_flash_carts_sram_old">Why SRAM works on emulators but doesn&#x27;t work with this old flash cart?</a></h3><p>While SRAM works out-of-the-box with most modern flash carts, it can fail with some older ones.</p><p>To fix it you can try to:</p><ul><li>Set save type as SRAM.</li><li>Disable or enable save patches.</li><li>Update the firmware of the flash cart.</li></ul></section></section>
      </div>
    </div>
  </div>
</article></main>
<div class="m-doc-search" id="search">
  <a href="#!" onclick="return hideSearch()"></a>
  <div class="m-container">
    <div class="m-row">
      <div class="m-col-m-8 m-push-m-2">
        <div class="m-doc-search-header m-text m-small">
          <div><span class="m-label m-default">Tab</span> / <span class="m-label m-default">T</span> to search, <span class="m-label m-default">Esc</span> to close</div>
          <div id="search-symbolcount">&hellip;</div>
        </div>
        <div class="m-doc-search-content">
          <form>
            <input type="search" name="q" id="search-input" placeholder="Loading &hellip;" disabled="disabled" autofocus="autofocus" autocomplete="off" spellcheck="false" />
          </form>
          <noscript class="m-text m-danger m-text-center">Unlike everything else in the docs, the search functionality <em>requires</em> JavaScript.</noscript>
          <div id="search-help" class="m-text m-dim m-text-center">
            <p class="m-noindent">Search for symbols, directories, files, pages or
            modules. You can omit any prefix from the symbol or file path; adding a
            <code>:</code> or <code>/</code> suffix lists all members of given symbol or
            directory.</p>
            <p class="m-noindent">Use <span class="m-label m-dim">&darr;</span>
            / <span class="m-label m-dim">&uarr;</span> to navigate through the list,
            <span class="m-label m-dim">Enter</span> to go.
            <span class="m-label m-dim">Tab</span> autocompletes common prefix, you can
            copy a link to the result using <span class="m-label m-dim">⌘</span>
            <span class="m-label m-dim">L</span> while <span class="m-label m-dim">⌘</span>
            <span class="m-label m-dim">M</span> produces a Markdown link.</p>
          </div>
          <div id="search-notfound" class="m-text m-warning m-text-center">Sorry, nothing was found.</div>
          <ul id="search-results"></ul>
        </div>
      </div>
    </div>
  </div>
</div>
<script src="search-v2.js"></script>
<script src="searchdata-v2.js" async="async"></script>
<footer><nav>
  <div class="m-container">
    <div class="m-row">
      <div class="m-col-l-10 m-push-l-1">
        <p>Butano Docs. Created with <a href="https://doxygen.org/">Doxygen</a> 1.14.0 and <a href="https://mcss.mosra.cz/">m.css</a>.</p>
      </div>
    </div>
  </div>
</nav></footer>
</body>
</html>
